
<!doctype html>
<html lang="zh" class="no-js">
  <head>
    
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width,initial-scale=1">
      
      
      
      
        <link rel="prev" href="../loadtest-jmeter/">
      
      
      
      <link rel="icon" href="../assets/images/favicon.png">
      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.20">
    
    
      
        <title>问题—原因—修复 Issues - 机器人调度系统文档</title>
      
    
    
      <link rel="stylesheet" href="../assets/stylesheets/main.e53b48f4.min.css">
      
        
        <link rel="stylesheet" href="../assets/stylesheets/palette.06af60db.min.css">
      
      


    
    
      
    
    
      
        
        
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
        <style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
      
    
    
      <link rel="stylesheet" href="../styles.css">
    
    <script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
    
      

    
    
    
  </head>
  
  
    
    
      
    
    
    
    
    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="cyan">
  
    
    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
    <label class="md-overlay" for="__drawer"></label>
    <div data-md-component="skip">
      
        
        <a href="#issues" class="md-skip">
          跳转至
        </a>
      
    </div>
    <div data-md-component="announce">
      
    </div>
    
    
      

  

<header class="md-header md-header--shadow" data-md-component="header">
  <nav class="md-header__inner md-grid" aria-label="页眉">
    <a href=".." title="机器人调度系统文档" class="md-header__button md-logo" aria-label="机器人调度系统文档" data-md-component="logo">
      
  
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>

    </a>
    <label class="md-header__button md-icon" for="__drawer">
      
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
    </label>
    <div class="md-header__title" data-md-component="header-title">
      <div class="md-header__ellipsis">
        <div class="md-header__topic">
          <span class="md-ellipsis">
            机器人调度系统文档
          </span>
        </div>
        <div class="md-header__topic" data-md-component="header-topic">
          <span class="md-ellipsis">
            
              问题—原因—修复 Issues
            
          </span>
        </div>
      </div>
    </div>
    
      
        <form class="md-header__option" data-md-component="palette">
  
    
    
    
    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="cyan"  aria-label="深色模式"  type="radio" name="__palette" id="__palette_0">
    
      <label class="md-header__button md-icon" title="深色模式" for="__palette_1" hidden>
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3zm3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95zm-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31"/></svg>
      </label>
    
  
    
    
    
    <input class="md-option" data-md-color-media="" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="cyan"  aria-label="亮色模式"  type="radio" name="__palette" id="__palette_1">
    
      <label class="md-header__button md-icon" title="亮色模式" for="__palette_0" hidden>
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5s-1.65.15-2.39.42zM3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29zm.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14zM20.65 7l-1.77 3.79a7.02 7.02 0 0 0-2.38-4.15zm-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29zM12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44z"/></svg>
      </label>
    
  
</form>
      
    
    
      <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
    
    
      <div class="md-header__option">
  <div class="md-select">
    
    <button class="md-header__button md-icon" aria-label="选择当前语言">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m12.87 15.07-2.54-2.51.03-.03A17.5 17.5 0 0 0 14.07 6H17V4h-7V2H8v2H1v2h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2zm-2.62 7 1.62-4.33L19.12 17z"/></svg>
    </button>
    <div class="md-select__inner">
      <ul class="md-select__list">
        
          <li class="md-select__item">
            <a href="./" hreflang="zh" class="md-select__link">
              中文
            </a>
          </li>
        
          <li class="md-select__item">
            <a href="../en/issues-rca/" hreflang="en" class="md-select__link">
              English
            </a>
          </li>
        
      </ul>
    </div>
  </div>
</div>
    
    
      
      
        <label class="md-header__button md-icon" for="__search">
          
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
        </label>
        <div class="md-search" data-md-component="search" role="dialog">
  <label class="md-search__overlay" for="__search"></label>
  <div class="md-search__inner" role="search">
    <form class="md-search__form" name="search">
      <input type="text" class="md-search__input" name="query" aria-label="搜索" placeholder="搜索" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
      <label class="md-search__icon md-icon" for="__search">
        
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
        
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
      </label>
      <nav class="md-search__options" aria-label="查找">
        
        <button type="reset" class="md-search__icon md-icon" title="清空当前内容" aria-label="清空当前内容" tabindex="-1">
          
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
        </button>
      </nav>
      
    </form>
    <div class="md-search__output">
      <div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
        <div class="md-search-result" data-md-component="search-result">
          <div class="md-search-result__meta">
            正在初始化搜索引擎
          </div>
          <ol class="md-search-result__list" role="presentation"></ol>
        </div>
      </div>
    </div>
  </div>
</div>
      
    
    
      <div class="md-header__source">
        <a href="https://gitee.com/Jimmy-chen-zheng/robot-interface-demo.git" title="前往仓库" class="md-source" data-md-component="source">
  <div class="md-source__icon md-icon">
    
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.0.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
  </div>
  <div class="md-source__repository">
    Gitee
  </div>
</a>
      </div>
    
  </nav>
  
</header>
    
    <div class="md-container" data-md-component="container">
      
      
        
          
        
      
      <main class="md-main" data-md-component="main">
        <div class="md-main__inner md-grid">
          
            
              
              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    



  

<nav class="md-nav md-nav--primary md-nav--integrated" aria-label="导航栏" data-md-level="0">
  <label class="md-nav__title" for="__drawer">
    <a href=".." title="机器人调度系统文档" class="md-nav__button md-logo" aria-label="机器人调度系统文档" data-md-component="logo">
      
  
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>

    </a>
    机器人调度系统文档
  </label>
  
    <div class="md-nav__source">
      <a href="https://gitee.com/Jimmy-chen-zheng/robot-interface-demo.git" title="前往仓库" class="md-source" data-md-component="source">
  <div class="md-source__icon md-icon">
    
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.0.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
  </div>
  <div class="md-source__repository">
    Gitee
  </div>
</a>
    </div>
  
  <ul class="md-nav__list" data-md-scrollfix>
    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href=".." class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    首页 Dashboard
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../overview/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    概览 Overview
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../live-demo/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    运行效果 Live Demo
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../config-nacos/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    配置中心 Nacos
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../observability/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    可观测性 SkyWalking
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../stability-sentinel/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    稳定性 Sentinel
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../mq-async/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    异步化 RabbitMQ
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../docker-deploy/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    容器化部署 Docker
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../loadtest-jmeter/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    压测 JMeter
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
    
  
  
  
    <li class="md-nav__item md-nav__item--active">
      
      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
      
      
        
      
      
        <label class="md-nav__link md-nav__link--active" for="__toc">
          
  
  
  <span class="md-ellipsis">
    问题—原因—修复 Issues
    
  </span>
  

          <span class="md-nav__icon md-icon"></span>
        </label>
      
      <a href="./" class="md-nav__link md-nav__link--active">
        
  
  
  <span class="md-ellipsis">
    问题—原因—修复 Issues
    
  </span>
  

      </a>
      
        

<nav class="md-nav md-nav--secondary" aria-label="目录">
  
  
  
    
  
  
    <label class="md-nav__title" for="__toc">
      <span class="md-nav__icon md-icon"></span>
      目录
    </label>
    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#0" class="md-nav__link">
    <span class="md-ellipsis">
      0.上线口径与压测基线
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#1-gateway-nacos-sentinel" class="md-nav__link">
    <span class="md-ellipsis">
      1. Gateway / Nacos / Sentinel
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#2" class="md-nav__link">
    <span class="md-ellipsis">
      2. 可观测性与基础设施
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#3" class="md-nav__link">
    <span class="md-ellipsis">
      3. 异步化与幂等
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#4-ruoyi-vue" class="md-nav__link">
    <span class="md-ellipsis">
      4. 代码与前端（RuoYi + Vue）
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#5" class="md-nav__link">
    <span class="md-ellipsis">
      5. 规约与治理（统一命名 &amp; 回溯）
    </span>
  </a>
  
</li>
      
    </ul>
  
</nav>
      
    </li>
  

    
  </ul>
</nav>
                  </div>
                </div>
              </div>
            
            
          
          
            <div class="md-content" data-md-component="content">
              <article class="md-content__inner md-typeset">
                
                  



<h1 id="issues">问题—原因—修复 Issues<a class="headerlink" href="#issues" title="Permanent link">&para;</a></h1>
<blockquote>
<p>环境说明：RuoYi-Cloud（ruoyi-modules-robot / ruoyi-api-robot），Gateway 统一入口 <code>/external/gs/**</code>；<br />
Nacos 注册与配置，Sentinel 动态规则，SkyWalking 全链路，可选 RabbitMQ 异步；Docker Compose 一键交付。</p>
</blockquote>
<hr />
<h2 id="0">0.上线口径与压测基线<a class="headerlink" href="#0" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>口径与基线不清</strong><br />
<strong>表现</strong>：不同同学对“成功/失败”“是否算 429”口径不一致，导致指标解读偏差。<br />
<strong>修复</strong>：统一口径与基线：  </li>
<li><strong>Dry-Run/关消费</strong>压测基线：100 QPS × 3 分钟，视 200/429 为成功（验证网关限流/稳定性）。  </li>
<li><strong>观测指标</strong>：P95/P99、Throughput、Error%、队列累积、SkyWalking Success Rate。  </li>
<li>
<p><strong>结果样例</strong>：18035 样本 <strong>P95=6ms</strong>、<strong>P99≈10ms</strong>、<strong>Error=0</strong>、Throughput≈<strong>100.2/s</strong>（多轮结果一致）。</p>
</li>
<li>
<p><strong>回滚与冷启动不可量化</strong><br />
<strong>修复</strong>：落库到《变更记录》：  </p>
</li>
<li><strong>冷启动</strong>：Docker Compose + 首启 SQL → <strong>≤ 12 分钟</strong> 新环境就绪；  </li>
<li><strong>回滚</strong>：微服务化后 <strong>≤ 5 分钟</strong>（回滚镜像/配置） 。</li>
</ul>
<hr />
<h2 id="1-gateway-nacos-sentinel">1. Gateway / Nacos / Sentinel<a class="headerlink" href="#1-gateway-nacos-sentinel" title="Permanent link">&para;</a></h2>
<ul>
<li>
<p><strong>Nacos 启动卡在 STARTING</strong><br />
<strong>原因</strong>：持久化 <strong>MySQL 版本/字符集不匹配</strong> 或未导入初始化 SQL。<br />
<strong>修复</strong>：补齐 <code>spring.datasource.*</code>，导入官方/项目初始化脚本；版本与镜像对齐（建议 <strong>2.2.x</strong>）。</p>
</li>
<li>
<p><strong>网关 404 / Swagger “Try it out” 失败</strong><br />
<strong>原因</strong>：<code>StripPrefix/Path</code> 与 <strong>下游 <code>context-path</code></strong> 不一致；服务前缀改动未更新路由。<br />
<strong>修复</strong>：统一路径策略；必要时<strong>移除</strong> <code>context-path</code> 或同步调整 Strip 规则；灰度后统一回收旧前缀。</p>
</li>
<li>
<p><strong>限流路径不一致，规则无法命中</strong><br />
<strong>原因</strong>：<code>@SentinelResource</code> <strong>分散在 Controller</strong>，资源名不统一。<br />
<strong>修复</strong>：统一下沉到 <strong><code>GsOpenApiServiceImpl</code></strong>；规范资源命名，并与 Nacos 规则一一对应<br />
  （如：<code>ruoyi-gateway-gw-api-defs/gw-flow/gw-degrade</code>）。</p>
</li>
<li>
<p><strong>Sentinel 规则不生效/分组空白</strong><br />
<strong>原因</strong>：缺 <code>sentinel-datasource-nacos</code> 依赖，或 <strong>DataId/Group 与 JSON</strong> 不一致。<br />
<strong>修复</strong>：补依赖；校验三元组 <code>{AppName, DataId, Group}</code> 与 JSON 结构；压测前提高网关阈值避免被 429 抢先挡掉。</p>
</li>
<li>
<p><strong>CORS 预检被拦</strong><br />
<strong>原因</strong>：未放行 <strong>OPTIONS</strong> 或响应头缺失。<br />
<strong>修复</strong>：配置全局 CORS：允许所需 <code>Origin/Headers/Methods</code>，暴露必要响应头；显式放行 <strong>OPTIONS</strong>。</p>
</li>
</ul>
<hr />
<h2 id="2">2. 可观测性与基础设施<a class="headerlink" href="#2" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>无 Gateway 链路 / 日志无 <code>traceId</code></strong><br />
<strong>原因</strong>：未加载 <strong>SCG/WebFlux 插件</strong>；<code>-javaagent</code> 未注入；Logback 无 MDC。<br />
<strong>修复</strong>：  </li>
<li>将 <code>apm-spring-cloud-gateway-3.x-plugin</code> 放入 <strong>plugins</strong>；  </li>
<li>启动加入 <code>-javaagent:/path/to/agent/agent.jar</code>；  </li>
<li>
<p>Logback Pattern 增加 <code>%X{traceId}</code>；压测期适当提高采样率，生产按 QPS 降噪。</p>
</li>
<li>
<p><strong>Docker：MySQL 端口冲突/首次无数据</strong><br />
<strong>原因</strong>：宿主占用 <code>3306</code> 或未导入 SQL。<br />
<strong>修复</strong>：调整端口映射或停宿主 MySQL；<strong>compose 预导入 SQL</strong>；增加 <code>healthcheck</code> 并让上游依赖 <code>depends_on.condition=service_healthy</code>。</p>
</li>
<li>
<p><strong>容器内访问失败（误用宿主 <code>localhost</code>）</strong><br />
<strong>原因</strong>：容器将宿主地址当本地。<br />
<strong>修复</strong>：容器间互调用 <strong>服务名:端口</strong>；访问宿主在 Win/Mac 使用 <code>host.docker.internal</code>。</p>
</li>
<li>
<p><strong>依赖/插件冲突（Reactor Netty 等）</strong><br />
<strong>原因</strong>：Spring Boot/Cloud 与依赖矩阵不一致。<br />
<strong>修复</strong>：锁定版本矩阵；仅按需引入 gateway/webflux/skywalking 插件并校验兼容性。</p>
</li>
</ul>
<hr />
<h2 id="3">3. 异步化与幂等<a class="headerlink" href="#3" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>压测时队列无限累积/消息重复消费</strong><br />
<strong>原因</strong>：演示环境 <strong>关消费（Dry-Run）</strong> 或缺少 <strong>prefetch/手动 ack</strong>；失败重试无上限。<br />
<strong>修复</strong>：  </li>
<li>压测口径：关消费只校验入口与可观测，允许累积；  </li>
<li>正式：开启消费者，设 <code>prefetch= n</code>、<strong>手动 ack</strong>，失败进入 <strong>DLQ</strong>；  </li>
<li>
<p>写操作引入<strong>幂等键</strong>，超时/重试<strong>禁止放大故障</strong>。</p>
</li>
<li>
<p><strong>RestTemplate 堆积/重试放大</strong><br />
<strong>原因</strong>：未设置超时与连接池，自动重试开启。<br />
<strong>修复</strong>：设置 <code>connect/read</code> 超时、连接池大小；禁用自动重试；关键写操作幂等化。</p>
</li>
</ul>
<hr />
<h2 id="4-ruoyi-vue">4. 代码与前端（RuoYi + Vue）<a class="headerlink" href="#4-ruoyi-vue" title="Permanent link">&para;</a></h2>
<ul>
<li>
<p><strong>MyBatis <code>Invalid bound statement</code></strong><br />
<strong>原因</strong>：<code>mapper-locations</code> 或 <strong>XML <code>namespace</code> ≠ 接口 FQN</strong>；XML 未打包。<br />
<strong>修复</strong>：校对 <code>@MapperScan + namespace</code>；确保 XML 被扫描与打包。</p>
</li>
<li>
<p><strong>前端跨域/端口不一致</strong><br />
<strong>原因</strong>：环境切换时 proxy 未同步。<br />
<strong>修复</strong>：<code>vue.config.js</code> 统一代理，端口/目标随环境变量切换。</p>
</li>
<li>
<p><strong>UI 小问题（来自阶段总结）</strong><br />
<strong>表现</strong>：分区/地图名换行、状态未自动刷新、接口结果结构不一致等。<br />
<strong>修复</strong>：  </p>
</li>
<li>表格列宽 + <code>tooltip</code> 优化；  </li>
<li>增加“手动刷新”（后续再上定时刷新）；  </li>
<li>API 返回做“字符串/对象”<strong>健壮解析</strong>，避免任务下发提示错误；  </li>
<li><code>areaId</code> 与坐标映射缺数据 → 与厂商对齐数据表，纳入后续里程碑。</li>
</ul>
<hr />
<h2 id="5">5. 规约与治理（统一命名 &amp; 回溯）<a class="headerlink" href="#5" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>资源命名/日志字段不统一，排障困难</strong><br />
<strong>修复</strong>：  </li>
<li>统一资源命名（与 Sentinel 规则一致），统一异常体；  </li>
<li>日志注入 <code>traceId</code>、<code>requestId</code>、<code>taskId</code>、<code>resource</code>；  </li>
<li>复盘流程：<strong>先交付后演进</strong>，变更与回滚留痕，按“问题→原因→修复”固化到文档。</li>
</ul>
<hr />
<h3 id="_1">附：可复用清单（上线前自检）<a class="headerlink" href="#_1" title="Permanent link">&para;</a></h3>
<ul>
<li>[ ] <code>gateway</code> 路由/前缀 与下游路径一致；  </li>
<li>[ ] Nacos 规则（DataId/Group）与应用资源名一致；  </li>
<li>[ ] SkyWalking <code>-javaagent</code> 与 Gateway/WebFlux 插件到位；  </li>
<li>[ ] Docker <code>healthcheck</code> 完整，首次启动 SQL 自动导入；  </li>
<li>[ ] 关消费压测口径/观测指标一致，正式环境开启消费者并配好 DLQ；  </li>
<li>[ ] CORS、超时、连接池、幂等与重试策略到位；  </li>
<li>[ ] 日志包含 trace 字段，可实现 <strong>trace ↔ log</strong> 互查。</li>
</ul>
<blockquote>
<p>指标来源：阶段总结与演示压测记录（基线 100 QPS，P95≈6ms，P99≈9–10ms，Error=0）。</p>
</blockquote>












                
              </article>
            </div>
          
          
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
        </div>
        
          <button type="button" class="md-top md-icon" data-md-component="top" hidden>
  
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
  回到页面顶部
</button>
        
      </main>
      
        <footer class="md-footer">
  
    
      
      <nav class="md-footer__inner md-grid" aria-label="页脚" >
        
          
          <a href="../loadtest-jmeter/" class="md-footer__link md-footer__link--prev" aria-label="上一页: 压测 JMeter">
            <div class="md-footer__button md-icon">
              
              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
            </div>
            <div class="md-footer__title">
              <span class="md-footer__direction">
                上一页
              </span>
              <div class="md-ellipsis">
                压测 JMeter
              </div>
            </div>
          </a>
        
        
      </nav>
    
  
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      <div class="md-copyright">
  
    <div class="md-copyright__highlight">
      © 2025 陈峥 Jimmy Chen · <a href="/legal/license/">MIT License</a>
    </div>
  
  
    Made with
    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
      Material for MkDocs
    </a>
  
</div>
      
        
<div class="md-social">
  
    
    
    
    
    <a href="https://github.com/JimmyZChen" target="_blank" rel="noopener" title="GitHub" class="md-social__link">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2A10 10 0 0 0 2 12c0 4.42 2.87 8.17 6.84 9.5.5.08.66-.23.66-.5v-1.69c-2.77.6-3.36-1.34-3.36-1.34-.46-1.16-1.11-1.47-1.11-1.47-.91-.62.07-.6.07-.6 1 .07 1.53 1.03 1.53 1.03.87 1.52 2.34 1.07 2.91.83.09-.65.35-1.09.63-1.34-2.22-.25-4.55-1.11-4.55-4.92 0-1.11.38-2 1.03-2.71-.1-.25-.45-1.29.1-2.64 0 0 .84-.27 2.75 1.02.79-.22 1.65-.33 2.5-.33s1.71.11 2.5.33c1.91-1.29 2.75-1.02 2.75-1.02.55 1.35.2 2.39.1 2.64.65.71 1.03 1.6 1.03 2.71 0 3.82-2.34 4.66-4.57 4.91.36.31.69.92.69 1.85V21c0 .27.16.59.67.5C19.14 20.16 22 16.42 22 12A10 10 0 0 0 12 2"/></svg>
    </a>
  
    
    
    
    
    <a href="https://gitee.com/Jimmy-chen-zheng" target="_blank" rel="noopener" title="Gitee" class="md-social__link">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M11.984 0A12 12 0 0 0 0 12a12 12 0 0 0 12 12 12 12 0 0 0 12-12A12 12 0 0 0 12 0zm6.09 5.333c.328 0 .593.266.592.593v1.482a.594.594 0 0 1-.593.592H9.777c-.982 0-1.778.796-1.778 1.778v5.63c0 .327.266.592.593.592h5.63c.982 0 1.778-.796 1.778-1.778v-.296a.593.593 0 0 0-.592-.593h-4.15a.59.59 0 0 1-.592-.592v-1.482a.593.593 0 0 1 .593-.592h6.815c.327 0 .593.265.593.592v3.408a4 4 0 0 1-4 4H5.926a.593.593 0 0 1-.593-.593V9.778a4.444 4.444 0 0 1 4.445-4.444h8.296Z"/></svg>
    </a>
  
    
    
    
    
    <a href="mailto:chenzheng2024xm@163.com" target="_blank" rel="noopener" title="Email" class="md-social__link">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m20 8-8 5-8-5V6l8 5 8-5m0-2H4c-1.11 0-2 .89-2 2v12a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V6a2 2 0 0 0-2-2"/></svg>
    </a>
  
    
    
    
    
    <a href="https://www.linkedin.com/in/jimmy-chen-74a8182b8/" target="_blank" rel="noopener" title="LinkedIn" class="md-social__link">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 3a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2zm-.5 15.5v-5.3a3.26 3.26 0 0 0-3.26-3.26c-.85 0-1.84.52-2.32 1.3v-1.11h-2.79v8.37h2.79v-4.93c0-.77.62-1.4 1.39-1.4a1.4 1.4 0 0 1 1.4 1.4v4.93zM6.88 8.56a1.68 1.68 0 0 0 1.68-1.68c0-.93-.75-1.69-1.68-1.69a1.69 1.69 0 0 0-1.69 1.69c0 .93.76 1.68 1.69 1.68m1.39 9.94v-8.37H5.5v8.37z"/></svg>
    </a>
  
</div>
      
    </div>
  </div>
</footer>
      
    </div>
    <div class="md-dialog" data-md-component="dialog">
      <div class="md-dialog__inner md-typeset"></div>
    </div>
    
    
    
      
      <script id="__config" type="application/json">{"base": "..", "features": ["navigation.instant", "navigation.sections", "content.code.copy", "content.image.zoom", "content.image.lightbox", "toc.integrate", "navigation.footer", "navigation.top"], "search": "../assets/javascripts/workers/search.973d3a69.min.js", "tags": null, "translations": {"clipboard.copied": "\u5df2\u590d\u5236", "clipboard.copy": "\u590d\u5236", "search.result.more.one": "\u5728\u8be5\u9875\u4e0a\u8fd8\u6709 1 \u4e2a\u7b26\u5408\u6761\u4ef6\u7684\u7ed3\u679c", "search.result.more.other": "\u5728\u8be5\u9875\u4e0a\u8fd8\u6709 # \u4e2a\u7b26\u5408\u6761\u4ef6\u7684\u7ed3\u679c", "search.result.none": "\u6ca1\u6709\u627e\u5230\u7b26\u5408\u6761\u4ef6\u7684\u7ed3\u679c", "search.result.one": "\u627e\u5230 1 \u4e2a\u7b26\u5408\u6761\u4ef6\u7684\u7ed3\u679c", "search.result.other": "# \u4e2a\u7b26\u5408\u6761\u4ef6\u7684\u7ed3\u679c", "search.result.placeholder": "\u952e\u5165\u4ee5\u5f00\u59cb\u641c\u7d22", "search.result.term.missing": "\u7f3a\u5c11", "select.version": "\u9009\u62e9\u5f53\u524d\u7248\u672c"}, "version": null}</script>
    
    
      <script src="../assets/javascripts/bundle.f55a23d4.min.js"></script>
      
        <script src="../move-palette.js"></script>
      
    
  </body>
</html>